@ceedcv-maya/shared-editor-react 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maya-AQSS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @ceedcv-maya/shared-editor-react
+
+Unified TipTap editor for the Maya ecosystem.
+
+## Components
+
+- **`<MayaEditor mode="lite" | "full" />`** — single editor with two visual modes. `lite` for short comments and alerts; `full` for templates and documents (BlockNote parity).
+- **`<EditorContentHtml html />`** — read-only renderer with DOMPurify sanitisation (aligned with the server-side `TiptapHtmlRenderer`).
+- **`<EditorToolbar />`** — toolbar builder, used internally by `MayaEditor` and exposed for custom integrations.
+
+## Extensions
+
+- `IframeBlock` — sandboxed iframe block with optional domain allowlist.
+- `AlertBlock` — variants info / warning / success / danger.
+- `CommentMark` — anchored-comment mark (paired with `AnchoredCommentController` server-side).
+
+## Conversion
+
+- `convertBlockNoteToTiptap(blocks)` — legacy → ProseMirror conversion. Mirror of the PHP `Maya\Editor\Renderers\BlockNoteToTiptap`.
+
+## Document import & block splitting
+
+Helpers behind the "Import from Word → blocks" flow (`DocxBlockSplitter` in maya_dms):
+
+- `docxToHtml(file)` / `docxToHtmlResult(file)` — convert a `.docx` `File` to sanitised, editor-ready HTML via mammoth (loaded dynamically, ~430KB). `docxToHtmlResult` also returns mammoth's `messages` (warnings for unrecognised styles / track changes that may not import cleanly).
+- `splitHtmlIntoBlocks(html)` — split an HTML fragment into top-level `BlockChunk[]` (heading / paragraph / list / table / figure / blockquote / codeBlock / horizontalRule / other), preserving each element's `outerHTML` for a lossless round-trip. **List items are exploded one chunk per `<li>`** (re-wrapped in their `<ul>`/`<ol>`) so callers can assign each bullet to a different block. Empty whitespace/`<br>`-only paragraphs are flagged `isEmpty`.
+- `htmlToTiptapDoc(html, extensions?)` — convert HTML to a TipTap JSON doc using a headless editor with the canonical Maya extensions, so the round-trip matches what the live editor persists. Empty input yields a doc with one empty paragraph (TipTap's normalised empty state).
+- `buildMayaEditorExtensions(mode)` — the canonical TipTap extension list, shared by `MayaEditor` and `htmlToTiptapDoc` (single source of truth for the schema).
+
+```ts
+const html = await docxToHtml(file);
+const chunks = splitHtmlIntoBlocks(html).filter((c) => !c.isEmpty);
+// …user groups chunks into blocks…
+const doc = htmlToTiptapDoc(groupHtml); // → persist doc.content
+```
+
+Known mammoth limitations: track changes and comments are dropped; non-standard Word styles may not map. `docxToHtmlResult().messages` surfaces these.
+
+## Anchored comments
+
+- `getAnchorRange(editor, commentId)` / `setAnchorRange(editor, id, range)`
+- `rebaseAnchors(anchors, tr)` — applies a ProseMirror `Transaction.mapping` to a list of anchors and flags collapsed ones as invalid.
+
+## Sanitisation
+
+- `sanitizeEditorHtml(rawHtml)` — DOMPurify config covering the full set of tags emitted by `TiptapHtmlRenderer` (paragraph, headings, lists, tables, blockquote, code, images, iframes with `sandbox`, alerts).
+
+## Usage
+
+```tsx
+import { MayaEditor } from '@ceedcv-maya/shared-editor-react';
+
+<MayaEditor
+  mode="full"
+  initialContent={template.html}
+  editable={canEdit}
+  onChange={(html) => save(html)}
+  isDark={theme === 'dark'}
+/>
+```
+
+Lite mode for short comments:
+
+```tsx
+<MayaEditor mode="lite" initialContent={comment.body} onChange={setBody} />
+```

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@ceedcv-maya/shared-editor-react",
+  "version": "0.6.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "@tiptap/core": "^3.0.0",
+    "@tiptap/extension-color": "^3.0.0",
+    "@tiptap/extension-highlight": "^3.0.0",
+    "@tiptap/extension-image": "^3.0.0",
+    "@tiptap/extension-link": "^3.0.0",
+    "@tiptap/extension-table": "^3.0.0",
+    "@tiptap/extension-table-cell": "^3.0.0",
+    "@tiptap/extension-table-header": "^3.0.0",
+    "@tiptap/extension-table-row": "^3.0.0",
+    "@tiptap/extension-task-item": "^3.0.0",
+    "@tiptap/extension-task-list": "^3.0.0",
+    "@tiptap/extension-text-align": "^3.0.0",
+    "@tiptap/extension-text-style": "^3.0.0",
+    "@tiptap/extension-underline": "^3.0.0",
+    "@tiptap/pm": "^3.0.0",
+    "@tiptap/react": "^3.0.0",
+    "@tiptap/starter-kit": "^3.0.0",
+    "dompurify": "^3.0.0",
+    "mammoth": "^1.8.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mammoth": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/dompurify": "^3.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"no linter configured\""
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maya-AQSS/maya_platform.git",
+    "directory": "packages/js/shared-editor-react"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Unified rich-text editor for Maya: MayaEditor (TipTap) with lite/full modes, BlockNote→TipTap converter, HTML SSR renderer, anchored-comments support.",
+  "keywords": [
+    "react",
+    "tiptap",
+    "prosemirror",
+    "blocknote",
+    "editor",
+    "wysiwyg",
+    "ceedcv",
+    "maya"
+  ],
+  "author": {
+    "name": "CEEDCV",
+    "email": "info@ceedcv.es",
+    "homepage": "https://ceedcv.es"
+  },
+  "homepage": "https://github.com/Maya-AQSS/shared-editor-react#readme",
+  "bugs": {
+    "url": "https://github.com/Maya-AQSS/maya_platform/issues"
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "tsconfig.json"
+  ]
+}

package/src/components/ColorPicker.tsx

@@ -0,0 +1,100 @@
+import { useEffect, useRef, useState } from 'react';
+
+interface ColorPickerProps {
+  title: string;
+  /** Currently applied colour (used for the swatch indicator + state). */
+  value?: string | null;
+  /** Called with a 6-digit hex or `null` (clear). */
+  onSelect: (color: string | null) => void;
+  /** Glyph shown inside the trigger button (e.g. `A` for text, `▮` for bg). */
+  glyph: React.ReactNode;
+  clearLabel?: string;
+}
+
+const PALETTE: Array<{ value: string | null; label: string }> = [
+  { value: null, label: 'Default' },
+  { value: '#000000', label: 'Black' },
+  { value: '#5b5b5b', label: 'Grey' },
+  { value: '#ef4444', label: 'Red' },
+  { value: '#f97316', label: 'Orange' },
+  { value: '#f59e0b', label: 'Yellow' },
+  { value: '#10b981', label: 'Green' },
+  { value: '#06b6d4', label: 'Cyan' },
+  { value: '#3b82f6', label: 'Blue' },
+  { value: '#8b5cf6', label: 'Purple' },
+  { value: '#ec4899', label: 'Pink' },
+  { value: '#a16207', label: 'Brown' },
+];
+
+/**
+ * Lightweight palette popover used by the editor toolbar for text colour
+ * and highlight (background) selection. Closes on outside click, Escape,
+ * or after a swatch is chosen.
+ */
+export function ColorPicker({ title, value, onSelect, glyph, clearLabel = 'Default' }: ColorPickerProps) {
+  const [open, setOpen] = useState(false);
+  const wrapperRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    const onDocClick = (e: MouseEvent) => {
+      if (!wrapperRef.current?.contains(e.target as Node)) setOpen(false);
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('mousedown', onDocClick);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDocClick);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  const isActive = !!value;
+
+  return (
+    <div className="maya-editor-color" ref={wrapperRef}>
+      <button
+        type="button"
+        title={title}
+        aria-label={title}
+        aria-pressed={isActive ? 'true' : undefined}
+        aria-haspopup="true"
+        aria-expanded={open}
+        onClick={() => setOpen((v) => !v)}
+        className={`maya-editor-toolbar__btn maya-editor-color__btn${isActive ? ' is-active' : ''}`}
+      >
+        <span className="maya-editor-color__glyph">{glyph}</span>
+        <span
+          className="maya-editor-color__swatch"
+          style={value ? { background: value } : undefined}
+          aria-hidden
+        />
+      </button>
+      {open && (
+        <div className="maya-editor-color__panel" role="menu">
+          {PALETTE.map((item) => (
+            <button
+              key={item.value ?? '__default__'}
+              type="button"
+              role="menuitem"
+              className={`maya-editor-color__cell${value === item.value ? ' is-active' : ''}`}
+              title={item.value === null ? clearLabel : item.label}
+              aria-label={item.value === null ? clearLabel : item.label}
+              onClick={() => {
+                onSelect(item.value);
+                setOpen(false);
+              }}
+              style={
+                item.value === null
+                  ? { backgroundImage: 'linear-gradient(45deg, transparent 47%, #d33 47%, #d33 53%, transparent 53%)' }
+                  : { background: item.value }
+              }
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/CommentHoverPopover.tsx

@@ -0,0 +1,82 @@
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+export interface CommentHoverData {
+  /** Display name of the comment author. */
+  author?: string;
+  /** ISO/locale string shown under the author; consumer formats it. */
+  createdAt?: string;
+  /** Body of the comment (plain text, line breaks are honoured). */
+  body: string;
+}
+
+interface CommentHoverPopoverProps {
+  comment: CommentHoverData | null;
+  /** Viewport-relative coordinates of the highlighted span. */
+  anchorRect: DOMRect | null;
+  isDark?: boolean;
+  /** Optional close button label (used only for the aria-label). */
+  closeLabel?: string;
+}
+
+/**
+ * Tooltip-style popover anchored above an editor span carrying a
+ * `data-comment-id`. Renders via a portal so it escapes the editor's
+ * `overflow: hidden` clip box and isn't clipped by the wizard layout.
+ *
+ * Positioning: prefers the top edge of the highlighted span; flips below
+ * when there's no room above (within 16px viewport padding).
+ */
+export function CommentHoverPopover({
+  comment,
+  anchorRect,
+  isDark = false,
+  closeLabel = 'Close',
+}: CommentHoverPopoverProps) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [size, setSize] = useState<{ width: number; height: number } | null>(null);
+
+  useEffect(() => {
+    if (!ref.current || !comment) return;
+    const r = ref.current.getBoundingClientRect();
+    setSize({ width: r.width, height: r.height });
+  }, [comment?.body, comment?.author]);
+
+  if (!comment || !anchorRect || typeof document === 'undefined') return null;
+
+  const padding = 8;
+  const margin = 16;
+  const popoverW = size?.width ?? 280;
+  const popoverH = size?.height ?? 80;
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+
+  // Place above if there's room, otherwise below.
+  const placeAbove = anchorRect.top - popoverH - padding > margin;
+  const top = placeAbove
+    ? Math.max(margin, anchorRect.top - popoverH - padding)
+    : Math.min(vh - popoverH - margin, anchorRect.bottom + padding);
+
+  // Centre horizontally over the span; clamp to viewport.
+  const centerX = anchorRect.left + anchorRect.width / 2;
+  const left = Math.max(margin, Math.min(vw - popoverW - margin, centerX - popoverW / 2));
+
+  return createPortal(
+    <div
+      ref={ref}
+      className={`maya-comment-popover${isDark ? ' is-dark' : ''}`}
+      role="tooltip"
+      aria-label={closeLabel}
+      style={{ top, left, maxWidth: 320 }}
+    >
+      <div className="maya-comment-popover__header">
+        <span className="maya-comment-popover__author">{comment.author ?? 'Comentario'}</span>
+        {comment.createdAt && (
+          <span className="maya-comment-popover__date">{comment.createdAt}</span>
+        )}
+      </div>
+      <div className="maya-comment-popover__body">{comment.body}</div>
+    </div>,
+    document.body,
+  );
+}

package/src/components/EditorContentHtml.tsx

@@ -0,0 +1,29 @@
+import { useMemo } from 'react';
+import { sanitizeEditorHtml } from '../lib/dompurifyConfig';
+
+interface EditorContentHtmlProps {
+  /** Pre-rendered HTML (typically from server-side TiptapHtmlRenderer). */
+  html: string;
+  className?: string;
+}
+
+/**
+ * Renders pre-sanitised editor HTML. Use this for read-only views (PDF
+ * previews, validator views, search hit cards) — for editing, use
+ * `<MayaEditor />`.
+ *
+ * Sanitises with the package DOMPurify config (aligned with the SSR
+ * renderer) — defence in depth, not a substitute for server-side
+ * sanitisation.
+ */
+export function EditorContentHtml({ html, className }: EditorContentHtmlProps) {
+  const safeHtml = useMemo(() => sanitizeEditorHtml(html), [html]);
+  if (!safeHtml) return null;
+
+  return (
+    <div
+      className={className ?? 'maya-editor-content'}
+      dangerouslySetInnerHTML={{ __html: safeHtml }}
+    />
+  );
+}

package/src/components/EditorToolbar.tsx

@@ -0,0 +1,225 @@
+import type { Editor } from '@tiptap/react';
+import type { EditorMode } from '../types';
+import { Btn } from './EditorToolbarButton';
+import {
+  FormattingButtons,
+  AdvancedFormattingButtons,
+  AlignmentButtons,
+  IndentButtons,
+  HeadingButtons,
+  ListAndBlockButtons,
+  TableAndMediaButtons,
+  DocumentButtons,
+  ViewModeButtons,
+} from './EditorToolbarGroups';
+
+interface EditorToolbarProps {
+  editor: Editor | null;
+  mode: EditorMode;
+  isFullscreen?: boolean;
+  onToggleFullscreen?: () => void;
+  onInsertHtml?: () => void;
+  onInsertMarkdown?: () => void;
+  viewMode?: 'wysiwyg' | 'html' | 'markdown';
+  onImage?: () => void;
+  onImportDocx?: () => void;
+  onExportDocx?: () => void;
+  onAddComment?: () => void;
+  onToggleFind?: () => void;
+  labels?: ToolbarLabels;
+}
+
+export interface ToolbarLabels {
+  bold: string;
+  italic: string;
+  underline: string;
+  strike: string;
+  code: string;
+  link: string;
+  linkPrompt: string;
+  unlink: string;
+  heading1: string;
+  heading2: string;
+  heading3: string;
+  bulletList: string;
+  orderedList: string;
+  taskList: string;
+  blockquote: string;
+  codeBlock: string;
+  horizontalRule: string;
+  image: string;
+  table: string;
+  alert: string;
+  iframe: string;
+  iframePrompt: string;
+  fullscreen: string;
+  exitFullscreen: string;
+  insertHtml: string;
+  insertMarkdown: string;
+  alignLeft: string;
+  alignCenter: string;
+  alignRight: string;
+  alignJustify: string;
+  indent: string;
+  outdent: string;
+  textColor: string;
+  backgroundColor: string;
+  colorDefault: string;
+  undo: string;
+  redo: string;
+  uploadImage: string;
+  importDocx: string;
+  exportDocx: string;
+  addComment: string;
+  find: string;
+  findPlaceholder?: string;
+  replacePlaceholder?: string;
+  findNext?: string;
+  findPrev?: string;
+  replace?: string;
+  replaceAll?: string;
+  findClose?: string;
+  caseSensitive?: string;
+  findNone?: string;
+}
+
+const DEFAULT_LABELS: ToolbarLabels = {
+  bold: 'Bold',
+  italic: 'Italic',
+  underline: 'Underline',
+  strike: 'Strike',
+  code: 'Code',
+  link: 'Link',
+  linkPrompt: 'URL',
+  unlink: 'Unlink',
+  heading1: 'H1',
+  heading2: 'H2',
+  heading3: 'H3',
+  bulletList: 'Bullet list',
+  orderedList: 'Numbered list',
+  taskList: 'Task list',
+  blockquote: 'Quote',
+  codeBlock: 'Code block',
+  horizontalRule: 'HR',
+  image: 'Image',
+  table: 'Table',
+  alert: 'Alert',
+  iframe: 'Iframe',
+  iframePrompt: 'Iframe URL',
+  fullscreen: 'Fullscreen',
+  exitFullscreen: 'Exit fullscreen',
+  insertHtml: 'Insert HTML',
+  insertMarkdown: 'Insert Markdown',
+  alignLeft: 'Align left',
+  alignCenter: 'Align center',
+  alignRight: 'Align right',
+  alignJustify: 'Justify',
+  indent: 'Increase indent',
+  outdent: 'Decrease indent',
+  textColor: 'Text color',
+  backgroundColor: 'Highlight color',
+  colorDefault: 'Default color',
+  undo: 'Undo',
+  redo: 'Redo',
+  uploadImage: 'Insert image',
+  importDocx: 'Import Word (.docx)',
+  exportDocx: 'Export Word (.docx)',
+  addComment: 'Comment selection',
+  find: 'Find and replace',
+  findPlaceholder: 'Find',
+  replacePlaceholder: 'Replace with',
+  findNext: 'Next match',
+  findPrev: 'Previous match',
+  replace: 'Replace',
+  replaceAll: 'Replace all',
+  findClose: 'Close find',
+  caseSensitive: 'Match case',
+  findNone: 'No matches',
+};
+
+/**
+ * EditorToolbar is a wrapper component that composes focused button groups.
+ * Each group handles a logically distinct set of toolbar buttons, keeping
+ * individual files under the 400-line target per coding-style.md.
+ */
+export function EditorToolbar({
+  editor,
+  mode,
+  isFullscreen,
+  onToggleFullscreen,
+  onInsertHtml,
+  onInsertMarkdown,
+  viewMode = 'wysiwyg',
+  onImage,
+  onImportDocx,
+  onExportDocx,
+  onAddComment,
+  onToggleFind,
+  labels,
+}: EditorToolbarProps) {
+  if (!editor) return null;
+  const L = labels ?? DEFAULT_LABELS;
+
+  const isLite = mode === 'lite';
+
+  return (
+    <div className="maya-editor-toolbar" role="toolbar" aria-label="Editor toolbar">
+      <Btn
+        disabled={!editor.can().undo()}
+        onClick={() => editor.chain().focus().undo().run()}
+        title={L.undo}
+      >
+        ↶
+      </Btn>
+      <Btn
+        disabled={!editor.can().redo()}
+        onClick={() => editor.chain().focus().redo().run()}
+        title={L.redo}
+      >
+        ↷
+      </Btn>
+
+      <span className="maya-editor-toolbar__sep" aria-hidden />
+      <FormattingButtons editor={editor} labels={L} />
+
+      {!isLite && (
+        <>
+          <span className="maya-editor-toolbar__sep" aria-hidden />
+          <AdvancedFormattingButtons editor={editor} labels={L} />
+
+          <span className="maya-editor-toolbar__sep" aria-hidden />
+          <AlignmentButtons editor={editor} labels={L} />
+
+          <span className="maya-editor-toolbar__sep" aria-hidden />
+          <IndentButtons editor={editor} labels={L} />
+
+          <span className="maya-editor-toolbar__sep" aria-hidden />
+          <HeadingButtons editor={editor} labels={L} />
+          <ListAndBlockButtons editor={editor} labels={L} />
+          <TableAndMediaButtons editor={editor} labels={L} onImage={onImage} />
+
+          <span className="maya-editor-toolbar__sep" aria-hidden />
+          <DocumentButtons
+            editor={editor}
+            labels={L}
+            onImportDocx={onImportDocx}
+            onExportDocx={onExportDocx}
+            onAddComment={onAddComment}
+            onToggleFind={onToggleFind}
+          />
+
+          <span className="maya-editor-toolbar__sep" aria-hidden />
+          <ViewModeButtons
+            editor={editor}
+            labels={L}
+            viewMode={viewMode}
+            isFullscreen={isFullscreen}
+            onInsertHtml={onInsertHtml}
+            onInsertMarkdown={onInsertMarkdown}
+            onToggleFullscreen={onToggleFullscreen}
+          />
+        </>
+      )}
+    </div>
+  );
+}

package/src/components/EditorToolbarButton.tsx

@@ -0,0 +1,32 @@
+/**
+ * Toolbar button component used across EditorToolbar and its button groups.
+ */
+interface BtnProps {
+  active?: boolean;
+  disabled?: boolean;
+  onClick: () => void;
+  title: string;
+  children: React.ReactNode;
+}
+
+export function Btn({
+  active,
+  disabled,
+  onClick,
+  title,
+  children,
+}: BtnProps) {
+  return (
+    <button
+      type="button"
+      title={title}
+      aria-label={title}
+      aria-pressed={active ? 'true' : undefined}
+      disabled={disabled}
+      onClick={onClick}
+      className={`maya-editor-toolbar__btn${active ? ' is-active' : ''}`}
+    >
+      {children}
+    </button>
+  );
+}